RESTful API

一般的 API

GET /getItem
POST /createItem
DELETE /deleteItem/1

REST 架構風格的 API

GET /items
POST /items
DELETE /items/1

REST 是一種 設計風格 而非協議，只要滿足規範都能稱為 RESTful API

REST 核心概念

資源（Resource）

每個資源都是一個具體的對象，通常表示為 URL
例如，https://api.example.com/users/1 表示 ID 為 1 的用戶

使用標準 HTTP 動詞來表示操作類型

GET：取得資源（讀取）
POST：建立新資源（新增）
PUT：更新資源（整體修改）
PATCH：更新資源（部分修改）
DELETE：刪除資源

無狀態性（Statelessness）

每次請求應包含完成操作所需的所有資訊
伺服器不會保存客戶端的狀態

統一接口（Uniform Interface）

所有資源的操作方式一致
客戶端和伺服器之間的通訊方式是統一的

分層架構（Layered System）

客戶端不需知道伺服器後端的實現細節，可能有多層代理或負載均衡

可快取性（Cacheability）

伺服器可以透過 HTTP 標頭（如 Cache-Control）聲明資源是否可以快取，以提升效能

RESTful API 的 URI 設計

URI (統一資源識別符)

URI：Uniform Resource Identifier
是網路資源的唯一字元序列
子類包含 URL、URN
- URL：統一資源定位符，就是網址
- URN：統一資源名，像是 ISBN (國際標準書號)

資源名稱使用名詞

用名詞表達資源 e.g.
- GET/users：取得所有用戶
- GET/users/1：取得 ID 為 1 的用戶
- POST/users：新增用戶

避免使用動詞

正確：GET/users、POST/users
錯誤：GET/getUser、POST/createUser

階層關係

表示父子關係 e.g.
- GET/users/1/posts：取得 ID 為 1 的用戶發布的所有文章

使用複數形式

資源名稱應為複數，表示一組資源
- e.g. /users 表示多個用戶資源

RESTful API 範例

資源
- /books：表示所有書籍
- /books/{id}：表示某本特定的書
操作

HTTP 動詞	URI	說明
GET	/books	取得所有書籍。
GET	/books/1	取得 ID 為 1 的書籍。
POST	/books	新增一本書。
PUT	/books/1	更新 ID 為 1 的書籍。
DELETE	/books/1	刪除 ID 為 1 的書籍。

回應格式

{
  "id": 1,
  "title": "RESTful API Design",
  "author": "John Doe",
  "price": 19.99
}

索引

RESTful API